IDLffVideoWrite

The IDLffVideoWrite object creates a video file with an optional soundtrack. If you need to write animated GIF files, use the WRITE_GIF procedure instead.

The process for creating a video file is:

IDLffVideoWrite is not available with the IDL Virtual Machine or IDL Runtime distributions.

For more information on video, please see the Creating Video topic.

Superclasses

None.

Creation

See IDLffVideoWrite::Init.

Methods

This class has the following methods:

IDLffVideoWrite::Init

IDLffVideoWrite::AddVideoStream

IDLffVideoWrite::AddAudioStream

IDLffVideoWrite::GetCodecs

IDLffVideoWrite::GetFormats

IDLffVideoWrite::GetStreams

IDLffVideoWrite::Put

IDLffVideoWrite::SetMetadata

IDLffVideoWrite::Cleanup

In addition, this class inherits the methods of its superclasses (if any).

Examples

This example creates an MP4 video of a rotating surface graphic, and includes an audio track.

PRO surfaceVideo_ex

  file = 'surface.mp4'

  width = 500

  height = 500

  frames = 180

  fps = 30

  speed = 2

  samplerate = 22050L

 

  ; Create object and initialize video/audio streams

  oVid = IDLffVideoWrite(file)

  vidStream = oVid.AddVideoStream(width, height, fps)

  audStream = oVid.AddAudioStream(samplerate)

 

  ; Generate some audio

  audio = FINDGEN(samplerate * frames / fps)

  audio = SIN(audio * 2 * !PI / samplerate) * samplerate / 22

  audio = SIN(audio * 2 * !PI / samplerate * 1000)

  audio = FIX(30000 * audio)

  time = oVid.Put(audStream, audio)

 

  ; Generate video frames

  surf = SURFACE(/TEST, DIMENSIONS=[width,height])

  FOR i = 0, frames-1 DO BEGIN

    time = oVid.Put(vidStream, surf.CopyWindow())

    surf.Rotate, speed

  ENDFOR

  surf.Close

   

  ; Close the file

  oVid = 0

END

IDLffVideoWrite::Init

Initializes the object and creates the video file.

Syntax

Result = IDLffVideoWrite( Filename [, FORMAT=string])

Return Value

When this method is called indirectly, as in the previous syntax, the return value is an object reference to the newly-created object.

When called directly within a subclass Init method, the return value is 1 if initialization was successful, or zero otherwise.

Arguments

Filename

A string that specifies the full path and name of the video file (container format) to create. If the file already exists, it will be overwritten. You can specify the file type by including a filename extension or by setting the optional FORMAT keyword. The IDL-supported file type extensions are:

Extension

File Type

.avi

Audio Video Interleave

.mp4

MPEG-4

Note: For a list of all available file types, call IDLffVideoWrite::GetFormats.

Keywords

FORMAT

Set this keyword to a string that specifies the file type (container format) to create. You can also specify the file type by including a filename extension when setting Filename.The IDL-supported strings are:

String

File Type

'avi'

Audio Video Interleave

'mp4'

MPEG-4

Note: For a list of all available file types, call IDLffVideoWrite::GetFormats.

IDLffVideoWrite::AddVideoStream

This function method adds a new video stream to the file.

Syntax

Result = Obj.[IDLffVideoWrite::]AddVideoStream( Width, Height, Fps [, BIT_RATE=Value] [, CODEC=string] [, PRESET=string] [, PROFILE=string] [, TUNE=string] )

Return Value

Returns the index of the new stream.

Arguments

Width

The frame width in pixels.

Height

The frame height in pixels.

Fps

The frames per second at which the video file is meant to be played back.

Note: Very low frame rates (<5 FPS) can be problematic for many codecs and players. Rather than setting FPS this low, we recommend that you set some multiple of the desired frame rate and output each frame several times. Because of the way most codecs encode video, the increase in file size is usually negligible.

Keywords

BIT_RATE

The target output data rate of the video encoder, in bits per second. Larger values produce higher quality video, but larger files, up to the maximum bit rate. Actual results may be slightly larger or smaller.

Note: The maximum bit rate depends upon the codec, frame size, and frames-per-second. Setting bit rates higher than the maximum is harmless but will not result in a higher-quality video.

CODEC

Set this keyword to the codec to use for encoding the data. For a video stream in an AVI or MP4-format file, the default value is 'MP4'.

Note: For a list of all available codecs, call IDLffVideoWrite::GetCodecs.

PRESET

Set this keyword to a string that selects one of the built-in encoding presets for the H.264 video codec. Because the version of FFmpeg included with IDL does not support H.264, this argument is useful only if you have replaced the FFmpeg version. See Replacing the FFmpeg Version.

This argument is equivalent to the -vpre argument to the command-line FFmpeg utility. Valid values are:

ultrafast

slower

superfast

veryslow

veryfast

max

faster

placebo

fast

lossless_ultrafast

normal

lossless_fast

default

lossless_medium

medium

lossless_slow

hq

lossless_slower

slow

lossless_max

The 'lossless' presets will guarantee perfect video quality with a tradeoff between encoding speed and file size. All other values have a tradeoff between encoding speed and video quality, with fairly constant file size.

Note: Not all players that support H.264 can play lossless video.

PROFILE

Set this keyword to a string that selects one of the built-in profile presets for the H.264 video codec. Because the version of FFmpeg included with IDL does not support H.264, this argument is useful only if you have replaced the FFmpeg version. See Replacing the FFmpeg Version.

This argument is equivalent to the -profile argument to the command-line FFmpeg utility. Valid values are:

baseline

 high10

main

 high422

high

 high444

Note: Usage of profile is not compatible with lossless encoding.

Note: Certain devices may only support certain profiles.

TUNE

Set this keyword to a string that selects one of the built-in tuning presets for the H.264 video codec. Because the version of FFmpeg included with IDL does not support H.264, this argument is useful only if you have replaced the FFmpeg version. See Replacing the FFmpeg Version.

This argument is equivalent to the -tune argument to the command-line FFmpeg utility. Valid values are:

film

 psnr

animation

 ssim

grain

 fastdecode

stillimage

 zerolatency

IDLffVideoWrite::AddAudioStream

This function method adds a new audio stream to the file.

Interlacing Video and Audio

Nearly all video formats require audio (if any) to be interlaced in the file with video frames, but IDLffVideoWrite does not require the user to output audio and video data this way. To permit this behavior, video and audio data is kept in memory until it can be interlaced and written out to a file.

The key to minimizing memory use is to keep all of the streams in the video synchronized--alternately write out a frame of video and some fraction of a second of audio. If you must do all of one and then the other, outputting audio first requires less memory.

Syntax

Result = Obj.[IDLffVideoWrite::]AddAudioStream(Rate [, BIT_RATE=value] [, CHANNELS=value] [, CODEC=string])

Return Value

Returns the index of the new stream.

Arguments

Rate

The audio sample rate in Hertz. Not all values are guaranteed to work, depending upon the codec used. Suggested values are 44100 (CD quality), 22050, and 11025.

Keywords

BIT_RATE

The target output data rate of the audio encoder, in bits per second. Larger values produce higher quality audio, but larger files. Actual results may be slightly larger or smaller.

CHANNELS

Set this keyword to the number of audio channels in the stream. For example, 1 = mono, 2 = stereo.

CODEC

Set this keyword to the codec to use for encoding the data. For an audio stream in an AVI or MP4-format file, the default value is 'MP2'.

Note: If you add only audio streams to an IDLffVideoWrite object, you can only use the MPEG-4 container format (file type).

Note: For a list of all available codecs, call IDLffVideoWrite::GetCodecs.

IDLffVideoWrite::GetCodecs

This function method returns the list of codecs you may use to encode a video or audio stream.

Tip: You can call IDLffVideoWrite::GetCodecs as a static method, without needing to create an IDLffVideoWrite object. For example:

print, IDLffVideoWrite.GetCodecs()

Syntax

Result = Obj.[IDLffVideoWrite::]GetCodecs([/AUDIO] [, /LONG_NAMES] [, /VIDEO])

or, calling as a static method:

Result = IDLffVideoWrite.GetCodecs([/AUDIO] [, /LONG_NAMES] [, /VIDEO])

Return Value

Returns the available codecs as an array of strings. These strings are the same names accepted by the CODEC keyword of the AddVideoStream and AddAudioStream methods (unless the LONG_NAMES keyword is set).

Arguments

None

Keywords

AUDIO

Set this keyword to return only available audio codecs.

LONG_NAMES

Set this keyword to return longer, more descriptive names.

VIDEO

Set this keyword to return only available video codecs.

IDLffVideoWrite::GetFormats

This function method returns the video file types (container formats) you can create.

Tip: You can call IDLffVideoWrite::GetFormats as a static method, without needing to create an IDLffVideoWrite object. For example:

print, IDLffVideoWrite.GetFormats()

Syntax

Result = Obj.[IDLffVideoWrite::]GetFormats(/LONG_NAMES)

or, calling as a static method:

Result = IDLffVideoWrite.GetFormats(/LONG_NAMES)

Return Value

Returns a list of available file formats as an array of strings. These strings are the same names accepted by the FORMAT keyword of the Init method (unless the LONG_NAMES keyword is set).

Arguments

None

Keywords

LONG_NAMES

Set this keyword to return longer, more descriptive format names.

IDLffVideoWrite::Put

This function method writes data into the stream identified by Index.

Syntax

Result = Obj.[IDLffVideoWrite::]Put(Index, Data)

Return Value

A floating-point value giving the point in the timeline (in seconds) that was assigned to the given data.

Arguments

Index

The data stream index returned by the AddVideoStream or AddAudioStream methods.

Data

Use this argument to specify the data to be written to the stream.

For video, the data must be represented as bytes in the format [3,w,h] with w and h matching the stream's original width and height.

For audio, the data must be represented as 16-bit integers and arranged in an array of the format [n, s] to write s samples (as many as desired) into n channels (n must match the number of channels in the stream). If you are writing one channel, [1,s] and [s] are functionally equivalent, and both formats are accepted.

IDLffVideoWrite::GetStreams

This function method returns an array of structures describing each of the streams contained in the video file.

Syntax

Result = Obj.[IDLffVideoWrite::]GetStreams( )

Return Value

Returns an array of structures describing each of the streams contained in the video file. These structures are of the following format:

{

PID,      ; Program ID - The internal identifier for the stream

type,     ; 0=unknown, 1=video, 2=audio, 3=data

rate,     ; Rate in Hertz. For example, 25 FPS for video, or 44100 Hz for audio

width,    ; Video only. Width in pixels

height,   ; Video only. Height in pixels

channels, ; Audio only. Number of audio channels

codec,    ; String identifying the codec used

length,   ; Stream length in seconds

}

IDLffVideoWrite::SetMetadata

This method embeds a metadata string in the video file.

Note: You can not call the SetMetadata method after you call the Put method.

Syntax

Obj.[IDLffVideoWrite::]SetMetadata, Key, Value

Arguments

Key

A case-insensitive string value. Keys unsupported by the file format are ignored.

The following table lists the metadata keys recognized by the IDL-supported video file formats. Other formats may have their own list of recognized metadata keys.

Key

album

artist

comment

copyright

genre

title

Value

A string value.

Keywords

None

Example

oVid.SetMetadata, 'title', 'Yeti photographed by wildlife cam'

IDLffVideoWrite::Cleanup

This method finalizes and closes the file, and then destroys the object. The file is not playable until the object is destroyed.

Note: The Cleanup method will automatically be called when the object is destroyed (either using OBJ_DESTROY or Automatic Garbage Collection). You only need to call ::Cleanup if you are creating a custom subclass and you override the Cleanup method.

Syntax

Obj.[IDLffVideoWrite::]Cleanup

See Also

Creating Video, IDLffVideoRead, QUERY_VIDEO, READ_VIDEO, WRITE_VIDEO

Version History

8.1

Introduced

8.2

Added PRESET keyword to ::AddVideoStream method.

8.3

Allow ::GetCodecs and ::GetFormats to be called as static methods.